package math.vectorSpace;

/**
 * The Abstract VectorSpace Class.
 * All vector space subclasses must define their own operations.
 * Subclasses must also implement at least one constructor, which creates the
 * zero vector in the vector space. Subclasses should NOT provide documentation
 * for methods inherited from this interface as all the documentations are
 * provided. The documentations in this class outlines the functionality of
 * the classes that implements this interface, hence changing the
 * documentation means the programmer decided to change the functionality
 * of the method, which would defeat the purpose of implementing this interface.
 * The only exception is the toString class documentation, which should be
 * overriden to provide the format of the returned String.
 *
 * Last Updated: Nov 10, 2011
 * 
 * @param <V> 
 * @author Shimu Wu
 * @version 1.0
 */
public interface VectorSpace<V> {

    /**
     * Returns a new vector that is the negation (additive inverse)
     * of this vector.
     *
     * @return a new vector that represents this vector's additive inverse
     */
    public V invert();

    /**
     * Returns a new Vector3D that is the sum of this vector and
     * the given vector.
     *
     * @param v2 the other vector
     * @return a new vector that is the sum of this vector and
     * the given vector
     */
    public V add(V v2);

    /**
     * Returns a new vector that is the scalar multiple of this vector.
     *
     * @param c a real number used to scale the vector
     * @return a new vector that is this vector scaled by factor c
     */
    public V scale(double c);

    /**
     * Returns true if this vector and the given vector have the exact
     * same components. The components are compared in the following manner:
     * |v1.component - v2.component| < epsileon, where epsileon is the 
     * margin of error allowed for floating point round offs. 
     * See MathExtended's isEqual(arg1, arg2). (Note that this method
     * returns false if the two vectors are scalar multiples of each other.
     * Use isColinear if more appropriate). This method is called in
     * the isEqual(Object) method of this class.
     * 
     * @see MathExtended.isEqual(arg1, arg2)
     * @param v2 the other vector to be compared to this vector
     * @return true only if this vector's components are identical (within a
     * small margin of error) to the given vector's components
     */
    public boolean isEqual(V v2);

    /**
     * Returns true if and only if the given Object has the same type
     * as this Object, and this.isEqual(o) returns true.
     * 
     * @param o the object to be compared with this one
     * @return true if and only if the given Object is of the same type
     * as this, and this.isEqual(o) returns true.
     */
    @Override
    public boolean equals(Object o);

    /**
     * Returns the String representation of this vector
     *
     * @return the String representation of this vector
     */
    @Override
    public String toString();
}
